/*
 * sysmo 服务器节点状态回调接口
 * Copyright (C) 2009  YuLicheng
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

package org.sysmo.server.node;

/**
 *
 * 当节点状态改变时，外部逻辑需要定义的回调方法接口。如增加、删除或
 * 节点类型变迁等。
 * <br />
 *
 * 由于这些节点状态改变可能导致一个节点在不同节点列表之间迁移，因此需要使用
 * 回调方法来通知外部逻辑，使其能够执行相应的迁移等动作。这里的外部逻辑一般
 * 是指{@link org.sysmo.server.SysmoServer}。
 *
 * @author YuLicheng
 */
public interface NodeStateChangeListener {

    /**
     * 客户端与服务器正常断开（客户端关闭）。
     */
    final static int CLIENT_SHUTDOWN = 0;
    /**
     * 客户端与服务器连接异常终止。
     */
    final static int CLIENT_CONNECTION_ABORT = 1;

    /**
     * 等待加入的新客户端加入了被监控列表。当节点类型从{@link NewNode}
     * 转变为{@link ConnectedNode}后，此方法被调用，以通知外部逻辑将此
     * 节点从等待加入列表迁移到监控列表。
     *
     * @param oldNode 之前的等待加入的节点
     * @param newNode 新生成的已连接节点。
     */
    void nodeAdded(NewNode oldNode, ConnectedNode newNode);

    /**
     * 节点被删除。当节点被从监控列表删除时（无论对应的客户端是否连接）
     * 此方法被调用，以通知外部逻辑从监控列表中删除节点实例并销毁。
     *
     * @param node 被删除的节点。
     */
    void nodeRemoved(AddedNode node);
    
    /**
     * 当原来与服务器连接的节点断开连接时，此方法被调用。
     * 
     * @param node 断开连接的节点。
     * @param mode 断开原因。
     * @see #CLIENT_CONNECTION_ABORT
     * @see #CLIENT_SHUTDOWN
     */
    void nodeDisconnected(ConnectedNode node, int mode);
}
